﻿<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">

	<head>
		<meta content="text/html; charset=utf-8" http-equiv="Content-Type" />
		<title>SignalR Integration</title>
		<link type="text/css" rel="stylesheet" href="bootstrap.min.css" />
	</head>

	<body>

		<div class="document-contents">

			<h3>Introduction</h3>
			<p>
				<a href="http://www.nuget.org/packages/Abp.Web.SignalR" target="_blank">Abp.Web.SignalR</a> 
	nuget package makes it easily to use <strong>SignalR</strong> in ASP.NET Boilerplate based 
	applications. See
				<a href="http://www.asp.net/signalr" target="_blank">SignalR documentation</a> 
	for detailed information on SignalR.</p>
			<h3>Installation</h3>
			<h4>Server Side</h4>
			<p>Install
				<a href="http://www.nuget.org/packages/Abp.Web.SignalR" target="_blank">
					<strong>Abp.Web.SignalR</strong>
				</a> nuget package to your project (generally to your Web 
	layer) and add a <strong>dependency</strong> to your module:</p>
			<pre lang="cs">
<strong>[DependsOn(typeof(AbpWebSignalRModule))]</strong>
public class YourProjectWebModule : AbpModule
{
    //...
}
			</pre>

			<p>Then use <strong>MapSignalR</strong> method in your OWIN startup class as you 
always do:</p>

			<pre lang="cs">
<strong>[assembly: OwinStartup(typeof(Startup))]</strong>
namespace MyProject.Web
{
    public class Startup
    {
        public void Configuration(IAppBuilder app)
        {
            <strong>app.MapSignalR();</strong>

            //...
        }
    }
}</pre>
			<p>
				<strong>Note:</strong> Abp.Web.SignalR only depends on 
	Microsoft.AspNet.SignalR.Core package. So, you will also need to <strong>
	install</strong>
				<strong>
					<a href="https://www.nuget.org/packages/Microsoft.AspNet.SignalR" target="_blank">Microsoft.AspNet.SignalR</a>
				</strong> package to your 
	Web project if not installed before (See
				<a href="http://www.asp.net/signalr" target="_blank">SignalR documents</a> 
	for more).</p>
			<h4>Client Side</h4>
			<p>
				<strong>abp.signalr.js</strong> script should be included to the page. 
	It's located in <strong>
					<a href="https://www.nuget.org/packages/Abp.Web.Resources" target="_blank">
	Abp.Web.Resources</a>
				</strong> package (It's already installed in
				<a href="/Templates">startup templates</a>). We should include it after 
	signalr hubs:</p>
			<pre lang="xml">&lt;script src=&quot;~/signalr/hubs&quot;&gt;&lt;/script&gt;
<strong>&lt;script src=&quot;~/Abp/Framework/scripts/libs/abp.signalr.js&quot;&gt;&lt;/script&gt;</strong>
			</pre>
			<p>That's all. SignalR is properly configured and integrated to your 
	project.</p>
			<h3>Connection Establishment</h3>
			<p>ASP.NET Boilerplate <strong>automatically connects</strong> to the server (from the 
	client) when <strong>abp.signalr.js</strong> is included to your page. This 
	is generally fine. But there may be cases you don't want to it. You can add 
	these lines just before including <strong>abp.signalr.js</strong> to disable 
	auto connecting:</p>
			<pre lang="xml">&lt;script&gt;
    abp.signalr = abp.signalr || {};
    abp.signalr.<strong>autoConnect</strong> = false;
&lt;/script&gt;</pre>
			<p>In this case, you can call <strong>abp.signalr.connect()</strong> 
	function manually whenever you need to connect to the server.</p>
	<p>
	ASP.NET Boilerplate also <strong>automatically reconnects</strong> to the server (from the 
	client) when client disconnects, if <strong>abp.signalr.autoConnect</strong> is true.
	</p>
			<p>
				<strong>"abp.signalr.connected"</strong> global event is triggered when 
	client connects to the server. You can register to this event to take 
	actions when the connection is successfully established. See javascript
				<a href="/Pages/Documents/Javascript-API/Event-Bus">event bus documentation</a> 
	for more about client side events.</p>
			<h3>Built-In Features</h3>
			<p>You can use all power of SignalR in your applications. In addition,
				<strong>Abp.Web.SignalR</strong> package implements some built-in features.</p>
			<h4>Notification</h4>
			<p>
				<strong>Abp.Web.SignalR</strong> package implements <strong>
	IRealTimeNotifier</strong> to send real time notifications to clients (see
				<a href="/Pages/Documents/Notification-System">notification system</a>). 
	Thus, you users can get real time push notifications.</p>
			<h4>Online Clients</h4>
			<p>ASP.NET Boilerplate provides <strong>IOnlineClientManager</strong> to get 
	information about 
	online users (inject IOnlineClientManager and use GetByUserIdOrNull, GetAllClients, 
	IsOnline 
	methods for example). IOnlineClientManager needs a communication 
	infrastructure to properly work. <strong>Abp.Web.SignalR</strong> 
	package provides the infrastructure. So, you can inject and use IOnlineClientManager in any 
	layer of your application if SignalR is installed.</p>
			<h4>PascalCase vs. camelCase</h4>
			<p>Abp.Web.SignalR package overrides SignalR's default <strong>
	ContractResolver</strong> to use <strong>
	CamelCasePropertyNamesContractResolver</strong> on serialization. Thus, we 
	can have classes have <strong>PascalCase</strong> properties on the server 
	and use them as <strong>camelCase</strong> on the client for 
	sending/receiving objects (because camelCase is preferred notation in 
	javascript). If you want to ignore this for your classes in some assemblies, 
	then you can add those assemblies to 
	AbpSignalRContractResolver.<strong>IgnoredAssemblies</strong> list.</p>
			<h3>Your SignalR Code</h3>
			<p>
				<strong>Abp.Web.SignalR</strong> package also simplifies your SignalR 
	code. Assume that we want to add a Hub to our application:</p>
			<pre lang="cs">public class MyChatHub : Hub, <strong>ITransientDependency</strong>
{
    public IAbpSession AbpSession { get; set; }

    public ILogger Logger { get; set; }

    public MyChatHub()
    {
        AbpSession = NullAbpSession.Instance;
        Logger = NullLogger.Instance;
    }

    <strong>public void SendMessage(string message)
    {
        Clients.All.getMessage(string.Format(&quot;User {0}: {1}&quot;, AbpSession.UserId, message));
    }</strong>

    public async override Task OnConnected()
    {
        await base.OnConnected();
        Logger.Debug(&quot;A client connected to MyChatHub: &quot; + Context.ConnectionId);
    }

    public async override Task OnDisconnected(bool stopCalled)
    {
        await base.OnDisconnected(stopCalled);
        Logger.Debug(&quot;A client disconnected from MyChatHub: &quot; + Context.ConnectionId);
    }
}</pre>
			<p>We implemented <strong>ITransientDependency</strong> to simply register 
	our hub to <a href="/Pages/Documents/Dependency-Injection">dependency 
	injection</a> system (you can make it singleton based on your needs). We
				<a href="/Pages/Documents/Dependency-Injection#DocPropertyInjection">
	property-injected</a> the <a href="/Pages/Documents/Abp-Session">session</a> 
	and <a href="/Pages/Documents/Logging">logger</a>.</p>
			<p>
				<strong>SendMessage</strong> is a method of our hub that can be used by 
	clients. We call <strong>getMessage</strong> function of <strong>all</strong> 
	clients in this method. We can use <a href="/Pages/Documents/Abp-Session">AbpSession</a> to get current user id (if 
	user logged in) as you see. We also overrided <strong>OnConnected</strong> and 
				<strong>OnDisconnected</strong>, which is just for demonstration and not needed here actually.</p>
			<p>Here, the <strong>client side</strong> javascript code to send/receive 
	messages using our hub.</p>
			<pre lang="js">var chatHub = <strong>$.connection.myChatHub</strong>; //get a reference to the hub

<strong>chatHub.client.getMessage</strong> = function (message) { //register for incoming messages
    console.log(&#39;received message: &#39; + message);
};

abp.event.on(&#39;abp.signalr.connected&#39;, function() { //register for connect event
    <strong>chatHub.server.sendMessage("Hi everybody, I'm connected to the chat!");</strong> //send a message to the server
});</pre>
			<p>Then we can use <strong>chatHub</strong> anytime we need to send message to the server. 
	See
				<a href="http://www.asp.net/signalr" target="_blank">SignalR documentation</a> 
	for detailed information on SignalR.</p>

		</div>

	</body>

</html>
